.\" SPDX-License-Identifier: CC-BY-SA-4.0 or-later
.\" SPDX-FileCopyrightText: 2025 grommunio GmbH
.TH mod_fastcgi 4gx "" "Gromox" "Gromox admin references"
.SH Name
mod_fastcgi \(em http(8gx) handler for proxying requests to
FastCGI servers
.SH Description
mod_fastcgi can forward HTTP requests to one or more FastCGI servers when
certain URIs are requested. Take special note of the file suffix column
documented below; in particular, to override an entire directory, you may also
need to edit the table for mod_cache(4gx).
.SH Configuration directives
This component shares \fBhttp.cfg\fP. See http(8gx).
.SH URI map
The filemap that specifies which URIs to handle is \fBfastcgi.txt\fP,
which is searched for in \fIconfig_file_path\fP. The usual location is
/etc/gromox/fastcgi.txt.
.PP
Each line in this file consists of 7 columns separated by whitespace:
.IP \(bu 4
Domain or asterisk-based wildcard ("*", "*.example.com") to match the HTTP
Host: request header with.
.IP \(bu 4
URI path (prefix) to match
.IP \(bu 4
Mapped path that will be passed to the FastCGI executor. Note that the FastCGI
process may additionally have a document root setting that could map the path
one more time.
.IP \(bu 4
File suffix (without dot) to match on, e.g. \fIphp\fP.
.IP \(bu 4
A file to use as the default file for a directory (similar to Apache httpd's
DirectoryIndex).
.IP \(bu 4
A set of headers, separated by the pipe symbol \fB|\fP, which should be
forwarded to the CGI handler. In absence of any desired extra headers, a single
pipe can be used to fill the column.
.IP \(bu 4
An AF_LOCAL socket path to make the FastCGI request to.
.PP
If the file has no lines, no documents will be served this way.
If the file is absent however, a set of default entries will be used.
.SS Default entries
.nf
* /sync /usr/share/grommunio-sync php index.php | /run/php-fpm/php-grommunio-sync-fpm.sock
* /web /usr/share/grommunio-web php index.php | /run/php-fpm/php-grommunio-web-fpm.sock
* /dav /usr/share/grommunio-dav php index.php | /run/php-fpm/php-grommunio-dav-fpm.sock
.fi
.PP
\fBNOTE:\fP The path designated for FPM sockets varies between distributions,
and because some distributions \fIalso\fP have security policies that involve
path matching (e.g. via AppArmor), we are unable to choose a path that works
out-of-the-box on all distro-provided platform configurations without fail.
/run/php-fpm is used as the default in line with the Grommunio Appliance.
.SH Files
.IP \(bu 4
\fIconfig_file_path\fP/fastcgi.txt: Map specifying with paths mod_fastcgi
should react to, and which FastCGI backend to route requests to
.SH See also
\fBgromox\fP(7), \fBhttp\fP(8gx)
